﻿<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
  
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Table-Of-Content (TOC) Files | DocFX website </title>
    <meta name="viewport" content="width=device-width">
    <meta name="title" content="Table-Of-Content (TOC) Files | DocFX website ">
    <meta name="generator" content="docfx 2.37.0.0">
    
    <link rel="shortcut icon" href="../favicon.ico">
    <link rel="stylesheet" href="../styles/docfx.vendor.css">
    <link rel="stylesheet" href="../styles/docfx.css">
    <link rel="stylesheet" href="../styles/main.css">
    <meta property="docfx:navrel" content="../toc.html">
    <meta property="docfx:tocrel" content="toc.html">
    
    <meta property="docfx:rel" content="../">
    
  </head>
  <body data-spy="scroll" data-target="#affix" data-offset="120">
    <div id="wrapper">
      <header>
        
        <nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
          <div class="container">
            <div class="navbar-header">
              <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
              </button>
              
              <a class="navbar-brand" href="../index.html">
                <img id="logo" class="svg" src="../logo.svg" alt="">
              </a>
            </div>
            <div class="collapse navbar-collapse" id="navbar">
              <form class="navbar-form navbar-right" role="search" id="search">
                <div class="form-group">
                  <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
                </div>
              </form>
            </div>
          </div>
        </nav>
        
        <div class="subnav navbar navbar-default">
          <div class="container hide-when-search" id="breadcrumb">
            <ul class="breadcrumb">
              <li></li>
            </ul>
          </div>
        </div>
      </header>
      <div class="container body-content">
        
        <div id="search-results">
          <div class="search-list"></div>
          <div class="sr-items">
            <p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
          </div>
          <ul id="pagination"></ul>
        </div>
      </div>
      <div role="main" class="container body-content hide-when-search">
        
        <div class="sidenav hide-when-search">
          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
          <div class="sidetoggle collapse" id="sidetoggle">
            <div id="sidetoc"></div>
          </div>
        </div>
        <div class="article row grid-right">
          <div class="col-md-10">
            <article class="content wrap" id="_content" data-uid="intro_toc">
<h1 id="table-of-content-toc-files">Table-Of-Content (TOC) Files</h1>

<h2 id="introduction">Introduction</h2>
<p>DocFX supports processing Markdown files, which we call <em>Conceptual File</em>s, as well as structured data model in YAML or JSON format, which we call <em>Metadata File</em>s. Besides that, DocFX introduces a way to organize these files using <em>Table-Of-Content File</em>s, which we also call <em>TOC File</em>s, so that users can navigate through <em>Metadata File</em>s and <em>Conceptual File</em>s.</p>
<p><em>TOC File</em>s must have file name <code>toc.md</code> or <code>toc.yml</code>, notice that file name is case-insensitive.</p>
<h2 id="basic-format">Basic format</h2>
<h3 id="markdown-format-toc-tocmd">Markdown format TOC <code>toc.md</code></h3>
<p><code>toc.md</code> leverages Markdown <a href="http://daringfireball.net/projects/markdown/syntax#header">Atx-style headers</a> which use 1-6 hash characters at the start of the line to represent the TOC levels 1-6. We call each line starting with hash characters a <em>TOC Item</em>. A <em>TOC Item</em> with higher level is considered as the child of the nearest upper <em>TOC Item</em> with less level. A sample <code>toc.md</code> is as below:</p>
<pre><code class="lang-md"># [Header1](href)
## [Header1.1](href)
# Header2
## [Header2.1](href)
### [Header2.1.1](href)
## [Header2.2](href)
# @UidForAnArticle
</code></pre>
<p>For a <em>TOC Item</em>, it can be either plain text, or a <a href="http://daringfireball.net/projects/markdown/syntax#link">Markdown inline link</a>, or <code>@uid</code> as the shortcut for <a href="../spec/docfx_flavored_markdown.html#cross-reference">cross-referenced</a></p>
<p>Three kinds of links are supported:</p>
<ol>
<li>Absolute path, for example, <code>http://example.net</code>.</li>
<li>Relative path, for example, <code>../example.md</code>. This kind of link has several advanced usages and is described in detail <a href="#href-in-detail">below</a>.</li>
<li>URI with <code>xref</code> scheme, for example, <code>xref:System.String</code>, the value is the <code>uid</code> of the file to be <a href="../spec/docfx_flavored_markdown.html#cross-reference">cross-referenced</a>.</li>
</ol>
<h3 id="yaml-format-toc-tocyml">YAML format TOC <code>toc.yml</code></h3>
<pre><code class="lang-yml">- name: Topic1
  href: Topic1.md
- name: Topic2
  href: Topic2.md
  items:
    - name: Topic2_1
      href: Topic2_1.md
</code></pre>
<p>Comparing to <code>toc.md</code>, <code>toc.yml</code> represents a structured data model and conforms to the <a href="http://www.yaml.org/spec/1.2/spec.html">YAML standard</a>. It supports advanced functionalities.</p>
<h4 id="data-model-for-tocyml">Data model for <code>toc.yml</code></h4>
<p>The data model for <code>toc.yml</code> is an <strong>array</strong> of <em>TOC Item Object</em>s.</p>
<h5 id="toc-item-object"><em>TOC Item Object</em></h5>
<p><em>TOC Item Object</em> represents the data model for each <em>TOC Item</em>.</p>
<div class="NOTE">
<h5>Note</h5>
<p>All the property names are <strong>case sensitive</strong>.</p>
</div>
<table>
<thead>
<tr>
<th>Property Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>name</em></td>
<td>string</td>
<td>Specifies the title of the <em>TOC Item</em>.</td>
</tr>
<tr>
<td><em>href</em></td>
<td>string</td>
<td>Specifies the hyperlink of the <em>TOC Item</em>. When its value is another TOC file, it is a TOC include, and all the items inside the included toc are considered as the child of current <em>TOC Item</em></td>
</tr>
<tr>
<td><em>items</em></td>
<td><em>TOC Item Object</em></td>
<td>Specifies the children <em>TOC Items</em> of current <em>TOC Item</em>.</td>
</tr>
</tbody>
</table>
<p><strong>Advanced</strong>: These properties are useful when a TOC links another TOC, or links to a uid.</p>
<table>
<thead>
<tr>
<th>Property Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>topicHref</em></td>
<td>string</td>
<td>Specifies the topic href of the <em>TOC Item</em>. It is useful when <em>href</em> is linking to a folder or <em>tocHref</em> is used.</td>
</tr>
<tr>
<td><em>topicUid</em></td>
<td>string</td>
<td>Specifies the <code>uid</code> of the <em>topicHref</em> file. If the value is set, it overwrites the value of <em>topicHref</em>.</td>
</tr>
<tr>
<td><del><em>homepage</em></del> <strong>Deprecated</strong></td>
<td>string</td>
<td><del>Specifies the homepage of the <em>TOC Item</em>. It is useful when <em>href</em> is linking to a folder.</del> Use <em>topicHref</em> instead.</td>
</tr>
<tr>
<td><del><em>uid</em></del> <strong>Deprecated</strong></td>
<td>string</td>
<td><del>Specifies the <code>uid</code> of the referenced file. If the value is set, it overwrites the value of <em>href</em>.</del> Use <em>topicUid</em> instead.</td>
</tr>
<tr>
<td><del><em>homepageUid</em></del> <strong>Deprecated</strong></td>
<td>string</td>
<td><del>Specifies the <code>uid</code> of the homepage. If the value is set, it overwrites the value of <em>homepage</em>.</del> Use <em>topicUid</em> instead.</td>
</tr>
</tbody>
</table>
<h2 id="href-in-detail">Href in detail</h2>
<p>If a <em>TOC Item</em> is linking to some relative path, there are three cases:</p>
<ol>
<li>Linking to another <em>TOC File</em>, for example, <code>href: examples/toc.md</code>.</li>
<li>Linking to a folder, which means, the value of the link ends with <code>/</code> explicitly, for example, <code>href: examples/</code></li>
<li>Linking to some local file.</li>
</ol>
<p>Each case is described in detail below.</p>
<h3 id="link-to-another-toc-file">Link to another <em>TOC File</em></h3>
<p>If the <em>TOC Item</em> is linking to some other <em>TOC File</em>, it is considered as a placeholder of the referenced <em>TOC File</em>, and DocFX will extract content from that <em>TOC File</em> and insert into current <em>TOC Item</em> <strong>recursively</strong>.</p>
<p>This technique is always used when you want to combine several <em>TOC File</em>s into one single <em>TOC File</em>.</p>
<p>If <code>homepage</code> <strong>or</strong> <code>topicHref</code> is set for this <em>TOC Item</em>, it will be considered as the <code>href</code> of the expanded <em>TOC Item</em>.</p>
<p>For example, one <code>toc.yml</code> file is like below:</p>
<pre><code class="lang-yml">- name: How-to tutorials
  href: howto/toc.yml
  topicHref: howto/overview.md
</code></pre>
<p>It references to the <code>toc.yml</code> file under folder <code>howto</code>, with the following content:</p>
<pre><code class="lang-yaml">- name: &quot;How-to1&quot;
  href: howto1.md
- name: &quot;How-to2&quot;
  href: howto2.md
</code></pre>
<p>DocFX processes these <code>toc.yml</code> files and expands the uppder <code>toc.yml</code> file into:</p>
<pre><code class="lang-yaml">- name: How-to tutorials
  href: howto/overview.md
  topicHref: howto/overview.md
  items:
    - name: &quot;How-to1&quot;
      href: howto/howto1.md
      topichref: howto/howto1.md
    - name: &quot;How-to2&quot;
      href: howto/howto2.md
      topichref: howto/howto2.md
</code></pre>
<div class="NOTE">
<h5>Note</h5>
<p>The referenced <code>toc.yml</code> file under <code>howto</code> folder will not be transformed to the output folder even if it is included in <code>docfx.json</code>.</p>
</div>
<h3 id="link-to-a-folder">Link to a folder</h3>
<p>If the <em>Toc Item</em> is linking to a folder, ending with <code>/</code> explicitly, the link value for the <em>Toc Item</em> is determined in the following steps:</p>
<ol>
<li><p>If <del><code>homepage</code></del> <code>topicHref</code> or <del><code>homepageUid</code></del> <code>topicUid</code> is set, the link value is resolved to the relative path to <del><code>homepage</code></del> <code>topicHref</code></p>
</li>
<li><p>If <del><code>homepage</code></del> <code>topicHref</code> or <del><code>homepageUid</code></del> <code>topicUid</code> is not set, DocFX searches for <em>Toc File</em> under the folder, and get the first <a href="#link-to-local-file">relative link to local file</a> as the link value for current <em>Toc Item</em>. For example, if the <em>Toc Item</em> is <code>href: article/</code>, and the content of <code>article/toc.yml</code> is as follows:</p>
<pre><code class="lang-yaml">- name: Topic1
  href: topic1.md
</code></pre>
<p>The link value for the <em>Toc Item</em> is resolved to <code>article/topic1.md</code>.</p>
</li>
<li><p>If there is no <em>Toc File</em> under the folder, the link value keeps unchanged.</p>
</li>
</ol>
<h3 id="link-to-local-file">Link to local file</h3>
<p>If the <em>Toc Item</em> is linking to a local file, we call this local file <em>In-Toc File</em>. Make sure the file is included in <code>docfx.json</code>.</p>
<h2 id="not-in-toc-files">Not-In-Toc Files</h2>
<p>When a local file is not referenced by any <em>Toc Item</em>, we call this local file <em>Not-In-Toc File</em>. Its <em>TOC File</em> is the nearest <em>TOC File</em> in output folder from the same folder as the local file to the root output folder.</p>
<div id="disqus_thread"></div>
                <script>
                (function() { // DON'T EDIT BELOW THIS LINE
                var d = document, s = d.createElement('script');
                s.src = 'https://docfx-github.disqus.com/embed.js';
                s.setAttribute('data-timestamp', +new Date());
                (d.head || d.body).appendChild(s);
                })();
                </script>
                <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
            </article>
          </div>
          
          <div class="hidden-sm col-md-2" role="complementary">
            <div class="sideaffix">
              <div class="contribution">
                <ul class="nav">
                  <li>
                    <a href="#disqus_thread" class="contribution-link">0 Comments</a>
                  </li>
                </ul>
              </div>
              <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
              <!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
              </nav>
            </div>
          </div>
        </div>
      </div>
      
      <footer>
        <div class="grad-bottom"></div>
        <div class="footer">
          <div class="container">
            <span class="pull-right">
              <a href="#top">Back to top</a>
            </span>
            <span>Copyright © 2015-2018 Microsoft<br>Generated by <strong>DocFX</strong></span>
            
          </div>
        </div>
      </footer>
    </div>
    
    <script type="text/javascript" src="../styles/docfx.vendor.js"></script>
    <script type="text/javascript" src="../styles/docfx.js"></script>
    <script type="text/javascript" src="../styles/main.js"></script>
    <script id="dsq-count-scr" src="//docfx-github.disqus.com/count.js" async=""></script>
    
    <script>
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
    
      ga('create', 'UA-99241001-1', 'auto');
      ga('send', 'pageview');
    
    </script>
  </body>
</html>
